Summary

Implements #6 — HTTP API: POST /query/timeline and POST /query/compare so API consumers get the same incident workflows as the CLI (raglogs timeline, raglogs compare), without shelling out.

Motivation

The README documented FastAPI endpoints for explain, ask, clusters, and ingest, but timeline and compare were CLI-only. Integrations (automation, internal tools, a future web UI) need stable HTTP contracts and JSON aligned with the CLI’s --format json output.

What’s new

POST /query/timeline

• Pipeline parity with raglogs timeline: resolve_window → run_clustering → assemble_evidence → build_timeline.
• Request body (aligned with CLI flags):
  • Window: since or from_time / to_time (same as other query routes).
  • Optional: service, env, all_ingestions, ingestion_job_id.
  • format: json (default) or text.
• Response:
  • window, ingestion_job_id, all_ingestions, events[].
  • Each event includes CLI JSON fields plus label for the timeline column.
  • If format is text, a text field contains a plain-text rendering (no Rich/ANSI).

POST /query/compare

• Semantics parity with raglogs compare:
  • Either since + baseline (window A ends at request time; B is the same duration offset by baseline), or explicit window_a_* / window_b_* ISO datetimes.
  • Optional: service, env, all_ingestions, ingestion_job_id, format (json | text).
• Response:
  • Same structure as CLI JSON: window_a, window_b, cluster diff arrays, new_triggers, dropped_triggers.
  • Adds has_changes (boolean) for quick checks.
  • Trigger entries include only_in (a | b).
  • Optional text when format is text.

Implementation notes

• Route module naming: src/api/routes/compare_windows.py avoids clashing with src.core.compare.
• Lazy import of compare_windows inside the handler so unit tests can patch src.core.compare.differ.compare_windows the same way as explain_window (avoids a stale module-level binding).
• Plain timeline text: src/core/timeline/plain_text.py mirrors CLI layout without pulling Rich into the API layer.

Documentation

• README HTTP API table and curl examples for timeline and compare.
• Roadmap item for these endpoints removed (shipped).

Testing

• Extended tests/unit/test_api.py with coverage for:
  • Timeline: 200 + events, format=text + text, invalid ingestion_job_id → 400.
  • Compare: since/baseline JSON, missing window params → 400, format=text, invalid ingestion_job_id → 400.
• Full unit suite: make test-unit (225 tests) passes.

How to verify locally

# With DB + data as in README quick start
uvicorn src.api.app:app --host 0.0.0.0 --port 8000

curl -s -X POST http://localhost:8000/query/timeline \
  -H "Content-Type: application/json" \
  -d '{"since":"2h"}' | head -c 500

curl -s -X POST http://localhost:8000/query/compare \
  -H "Content-Type: application/json" \
  -d '{"since":"30m","baseline":"24h"}' | head -c 500

Checklist

• Endpoints registered under /query with existing tags
• Request validation and 400s for invalid windows / UUIDs
• README + OpenAPI via FastAPI for new routes
• Unit tests

Closes #6

Made with Cursor